ExcerptThis document provides readers with an understanding of how to use WAI-ARIA 1.1 [WAI-ARIA] to create accessible rich internet applications. It describes considerations that might not be evident to most authors from the WAI-ARIA specification alone and recommends approaches to make widgets, navigation, and behaviors accessible using WAI-ARIA roles, states, and properties. This document is directed primarily to Web application developers, but the guidance is also useful for user agent and assistive technology developers.
presentation.
<div>
has also incorporated JavaScript that
provides the keyboard interactions
expected for a button. Unlike HTML
input elements, ARIA roles do not
cause browsers to provide keyboard
behaviors or styling.
button
is wrapped in an element with
role
heading
that has a value set for
aria-level
that is appropriate for the
information architecture of the
page.
heading
and aria-level, such as an HTML
heading tag, a native
host language element
may be used.
button
element is the only
element inside the heading
element. That is, if
there are other visually
persistent elements,
they are not included
inside the heading
element.
button
element has
aria-expanded
set to true. If the panel is not visible,
aria-expanded
is set to false.
button
element has
aria-controls
set to the ID of the element
containing the accordion panel
content.
button
element has
aria-disabled
set to true.
region
role in circumstances
that create landmark
region proliferation,
e.g., in an accordion
that contains more than
approximately 6 panels
that can be expanded at
the same time.
region
is especially helpful to
the perception of
structure by screen
reader users when panels
contain heading elements
or a nested
accordion.
alertdialog
has either:
alertdialog
has a value set for
aria-describedby
that refers to the element
containing the alert
message.
page. If the element representing
the current page is not a link,
aria-current is optional.
menu
or true.
button
helps assistive technology users
understand the function of the
element. However, a better solution is
to adjust the visual design so it
matches the function and ARIA
role.
div
and span
elements made into accessible command
and toggle buttons.
button
has an accessible label. By
default, the accessible name is
computed from any text content
inside the button element.
However, it can also be provided
with
aria-labelledby
or
aria-label.
true, and when toggled off, the
state is false.
aria-roledescription
is set to "carousel",
the label does not contain the
word "carousel".
aria-pressed, specified.
aria-roledescription
is set to
"slide", the
label does not contain
the word
"slide."
false
and
aria-live
set to:
off: if the carousel is
automatically
rotating.
polite: if the carousel is NOT
automatically
rotating.
group, and it does not have the aria-roledescription
property.
tab
element, so activating a
tab displays the slide
associated with that
tab.
tab
indicates which slide it
will display by
including the name or
number of the slide,
e.g., "Slide
3". Slide names are
preferable if each slide
has a unique name.
tablist
element with an
accessible name provided
by the value of
aria-label
that identifies the
purpose of the tabs,
e.g., "Choose slide
to display."
group
element.
true. Note: aria-disabled
is preferable to the HTML disabled
attribute because this is a
circumstance where screen reader
users benefit from the disabled
button being included in the
page Tab sequence.
mixed
value for aria-checked
and group collection of
checkboxes with a field
set.
checkbox.
aria-autocomplete=none
and uses the ARIA 1.0
implementation pattern.
contenteditable
HTML attribute.
aria-activedescendant
as described in
Managing Focus in
Composites Using
aria-activedescendant.
aria-activedescendant
as described in
Managing Focus in
Composites Using
aria-activedescendant.
aria-activedescendant
as described in
Managing Focus in
Composites Using
aria-activedescendant.
aria-activedescendant
so DOM focus moves into the dialog
from the textbox.
listbox, the element with role combobox
has
aria-haspopup
set to a value that
corresponds to the popup
type. That is, aria-haspopup
is set to grid, tree, or dialog. Note that elements
with role combobox
have an implicit aria-haspopup
value of listbox.
combobox
has a value for
aria-haspopup
of listbox. Note that elements
with role combobox
have an implicit aria-haspopup
value of listbox.
false. Note that the default value
of aria-multiline
is false.
combobox
has
aria-expanded
set to false. When the popup element is
visible, aria-expanded
is set to true. Note that elements with role combobox
have a default value for aria-expanded
of false.
option, gridcell, row, or treeitem
containing that value has
aria-selected
set to true.
none: When the popup is
displayed, the suggested
values it contains are
the same regardless of
the characters typed in
the textbox.
list: When the popup is
triggered, it presents
suggested values that
complete or logically
correspond to the
characters typed in the
textbox.
both: When the popup is
triggered, it presents
suggested values that
complete or logically
correspond to the
characters typed in the
textbox. In addition,
the portion of the
selected suggestion that
has not been typed by
the user, known as the
completion string,
appears inline after the
input cursor in the
textbox. The inline
completion string is
visually highlighted and
has a selected
state.
tabindex
value of zero or greater. Note that
values greater than 0 are strongly
discouraged.
tabindex=-1
to a static element at
the top of the dialog,
such as the dialog title
or first paragraph, and
initially focus that
element.
button
that closes the dialog, such as
a close icon or cancel
button.
dialog.
dialog
role to indicate which element
or elements in the dialog
contain content that describes
the primary purpose or message
of the dialog. Specifying
descriptive elements enables
screen readers to announce the
description along with the
dialog title and initially
focused element when the dialog
opens.
true
can prevent users of some
assistive technologies from
perceiving content outside the
dialog, users of those
technologies will experience
severe negative ramifications if
a dialog is marked modal but
does not behave as a modal for
other users. So, mark a dialog
modal only when both:
aria-modal
property introduced by ARIA 1.1
replaces
aria-hidden
for informing assistive
technologies that content
outside a dialog is inert.
However, in legacy dialog
implementations where aria-hidden
is used to make content outside
a dialog inert for assistive
technology users, it is
important that:
aria-hidden
is set to true
on each element
containing a portion of
the inert layer.
aria-hidden
set to true.
button
has
aria-expanded
set to true. When the content area is
hidden, it is set to false.
button
has a value specified for
aria-controls
that refers to the element that
contains all the content that is
shown or hidden.
feed
role is not associated with any
well-established keyboard conventions.
Supporting the following, or a
similar, interface is
recommended.
feed
element has
aria-labelledby
referring to the element
containing the title. Otherwise,
the feed
element has a label specified
with
aria-label.
article
element.
article
element has
aria-labelledby
referring to elements inside the
article that can serve as a
distinguishing label.
article
element to have
aria-describedby
referring to one or more
elements inside the article that
serve as the primary content of
the article.
article
element has
aria-setsize
set to a value that represents
either the total number of
articles that have been loaded
or the total number in the feed,
depending on which value is
deemed more helpful to users. If
the total number in the feed is
undetermined, it can be
represented by a aria-setsize
value of -1.
article
elements are being added to or
removed from the feed
container, and if the operation
requires multiple DOM
operations, the feed
element has
aria-busy
set to true
during the update operation.
Note that it is extremely
important that aria-busy
is set to false
when the operation is complete
or the changes may not become
visible to some assistive
technology users.
grid
role, using the grid
role on an element does not
necessarily imply that its visual
presentation is tabular.
grid
pattern or the
table
pattern.
grid
is a composite widget so
it:
grid
pattern broadly fall into two
categories: presenting tabular
information (data grids) and grouping
other widgets (layout grids). Even
though both data grids and layout
grids employ the same ARIA roles,
states, and properties, differences in
their content and purpose surface
factors that are important to consider
in keyboard interaction design. To
address these factors, the following
two sections describe separate
keyboard interaction patterns for data
and layout grids.
grid
can be used to present tabular
information that has column titles,
row titles, or both. The grid
pattern is particularly useful if the
tabular information is editable or
interactive. For example, when data
elements are links to more
information, rather than presenting
them in a static table and including
the links in the tab sequence,
implementing the grid
pattern provides users with intuitive
and efficient keyboard navigation of
the grid contents as well as a shorter
tab sequence for the page. A grid
may also offer functions, such as cell
content editing, selection, cut, copy,
and paste.
grid
pattern can be used to group a set of
interactive elements, such as links,
buttons, or checkboxes. Since only one
element in the entire grid is included
in the tab sequence, grouping with a
grid can dramatically reduce the
number of tab stops on a page. This is
especially valuable if scrolling
through a list of elements dynamically
loads more of those elements from a
large data set, such as in a
continuous list of suggested products
on a shopping site. If elements in a
list like this were in the tab
sequence, keyboard users are
effectively trapped in the list. If
any elements in the group also have
associated elements that appear on
hover, the grid
pattern is also useful for providing
keyboard access to those contextual
elements of the user interface.
grid
used for layout does not necessarily
have header cells for labelling rows
or columns and might contain only a
single row or a single column. Even if
it has multiple rows and columns, it
may present a single, logically
homogenous set of elements. For
example, a list of recipients for a
message may be a grid where each cell
contains a link that represents a
recipient. The grid may initially have
a single row but then wrap into
multiple rows as recipients are added.
In such circumstances, grid navigation
keys may also wrap so the user can
read the list from beginning to end by
pressing either Right Arrow or Down
Arrow. While This type of focus
movement wrapping can be very helpful
in a layout grid, it would be
disorienting if used in a data grid,
especially for users of assistive
technologies.
grid, a grid
is both easier to build and use if the
components it contains do not require
the arrow keys to operate. If a cell
contains an element like a
listbox, then an extra key command to focus
and activate the listbox is needed as
well as a command for restoring the
grid navigation functionality.
Approaches to supporting this need are
described in the section on
Editing and Navigating Inside a
Cell.
row
element and has one of the
following roles:
true. If the grid supports column
selection and a column is
selected, all cells in the
column have aria-selected
set to true.
true
on cells where editing is
disabled. If edit functions are
disabled for all cells, aria-readonly
may be set true
on the grid element. Grids that
do not provide editing functions
do not include the aria-readonly
attribute on any of their
elements.
grid
role is NOT applied to an HTML table
element, then
aria-rowspan
or
aria-colspan
is applied as described in
grid and table
properties.
grid
role is an HTML table
element, then it is not
necessary to use ARIA roles for
rows and cells because the HTML
elements have implied ARIA
semantics. For example, an HTML <TR>
has an implied ARIA role of row. A grid
built from an HTML table
that includes cells that span
multiple rows or columns must
use HTML rowspan
and colspan
and must not use aria-rowspan
or aria-colspan.
grid
element unless the DOM
descendants are also included in
the aria-owns
attribute.
<A>
element with an href
attribute. As with other WAI-ARIA
widget roles, applying the link role
to an element will not cause browsers
to enhance the element with standard
link behaviors, such as navigation to
the link target or context menu
actions. When using the link
role, providing these features of the
element is the author's
responsibility.
select
with size
attribute greater than
one.
select
with the attribute size="1".
listbox
role supports the
aria-activedescendant
property, which provides an
alternative to moving DOM focus
among option
elements when implementing
keyboard navigation. For
details, see
Managing Focus in
Composites Using
aria-activedescendant.
listbox.
listbox
has
aria-orientation
set to horizontal. The default value of aria-orientation
for listbox
is vertical.
radio
element has
aria-checked
set to true. If it is not checked, it has
aria-checked
set to false.
radio
element is labelled by its
content, has a visible label
referenced by
aria-labelledby, or has a label specified with
aria-label.
radiogroup
element has a visible label
referenced by
aria-labelledby
or has a label specified with
aria-label.
radiogroup
element or radio
elements with the
aria-describedby
property.
aria-valuenow
is not user-friendly, e.g., the
day of the week is represented
by a number, the
aria-valuetext
property is set to a string that
makes the slider value
understandable, e.g.,
"Monday".
vertical. The default value of aria-orientation
for a slider is horizontal.
aria-valuenow
is not user-friendly, e.g., the
day of the week is represented
by a number, the
aria-valuetext
property is set to a string that
makes the slider value
understandable, e.g.,
"Monday".
vertical. The default value of aria-orientation
for a slider is horizontal.
contenteditable
HTML attribute.
aria-valuenow
is not user-friendly, e.g., the
day of the week is represented
by a number, the
aria-valuetext
property is set on the
spinbutton element to a string
that makes the spinbutton value
understandable, e.g.,
"Monday".
true
if the value is outside the
allowed range. Note that most
implementations prevent input of
invalid values, but in some
scenarios, blocking all invalid
input may not be
practical.
table
element, a WAI-ARIA
table
is a static tabular structure
containing one or more rows that each
contain one or more cells; it is not
an interactive widget. Thus, its cells
are not focusable or selectable. The
grid pattern
is used to make an interactive widget
that has a tabular structure.
table
element whenever possible. This is
especially important with role table
because it is a new feature of
WAI-ARIA 1.1. It is thus advisable to
test implementations thoroughly with
each browser and assistive technology
combination that could be used by the
target audience.
row
element and has one of the
following roles:
table
element unless the DOM descendants are
also included in the aria-owns
attribute.
tab
element. When the tab list
contains the focus, moves focus
to the next element in the page
tab sequence outside the
tablist, which is typically
either the first focusable
element inside the tab panel or
the tab panel itself.
tablist.
tablist
has
aria-labelledby
set to a value that refers to
the labelling element.
Otherwise, the tablist
element has a label provided by
aria-label.
tab
has the property
aria-controls
referring to its associated tabpanel
element.
tab
element has the state
aria-selected
set to true
and all other tab
elements have it set to false.
tabpanel
has the property
aria-labelledby
referring to its associated tab
element.
tablist
element is vertically oriented,
it has the property
aria-orientation
set to vertical. The default value of aria-orientation
for a tablist
element is horizontal.
toolbar
role can be used to communicate the
presence and purpose of the grouping
to screen reader users. Grouping
controls into toolbars can also be an
effective way of reducing the number
of tab stops in the keyboard
interface.
vertical. The default orientation is
horizontal.
aria-level, aria-posinset
and aria-setsize
based on DOM structure.
aria-level, aria-posinset
and aria-setsize.
aria-level, aria-posinset
and aria-setsize
based on DOM structure.
aria-level, aria-posinset
and aria-setsize.
tree
role supports the
aria-activedescendant
property, which provides an
alternative to moving DOM focus
among treeitem
elements when implementing
keyboard navigation. For
details, see
Managing Focus in
Composites Using
aria-activedescendant.
tree
or referenced by an
aria-owns
property set on the tree
element.
treeitem
that serves as a parent node has
aria-expanded
set to false
when the node is in a closed
state and set to true
when the node is in an open
state. End nodes do not have the aria-expanded
attribute because, if they were
to have it, they would be
incorrectly described to
assistive technologies as parent
nodes.
tree
has
aria-multiselectable
set to true. Otherwise, aria-multiselectable
is either set to false
or the default value of false
is implied.
true
for the selected node and it is
not present on any other node in
the tree.
aria-selected
state.
tree
has either a visible label
referenced by
aria-labelledby
or a value specified for
aria-label.
tree
element is horizontally
oriented, it has
aria-orientation
set to horizontal. The default value of aria-orientation
for a tree is vertical.
treegrid
used to display messages and message
responses for a e-mail discussion
list, messages with responses would be
in rows that can be expanded to reveal
the response messages.
treegrid
that are either not focusable or not
used to label a column or row.
treegrid, a visual keyboard indicator informs
the user which row or cell is focused.
If the treegrid
allows the user to choose just one
item for an action, then it is known
as a single-select treegrid, and the item with focus also has a
selected state. However, in
multi-select treegrids, which enable the user to select
more than one row or cell for an
action, the selected state is
independent of the focus. For example,
in a hierarchical e-mail discussion
grid, the user can move focus to
select any number of rows for an
action, such as delete or move. It is
important that the visual design
distinguish between items that are
selected and the item that has focus.
For more details, see
this description of differences
between focus and selection.
treegrid
Example: A treegrid for navigating an
e-mail inbox that demonstrates
three keyboard navigation models
-- rows first, cells first, and
cells only.
treegrid
navigation by moving focus among rows
and cells of the grid. Implementations
of treegrid
make these key commands available when
an element in the grid has received
focus, e.g., after a user has moved
focus to the grid with Tab. Moving
focus into the grid may result in the
first cell or the first row being
focused. Whether focus goes to a cell
or the row depends on author
preferences and whether row focus is
supported, since some treegrids may not provide focus to
rows.
aria-expanded
property, opens or closes the
child rows.,Otherwise, performs
the default action for the
cell.
treegrid
widget to the next focusable
element.
treegrid
navigation keys move focus,
whether the focus is set on an
element inside the cell or on
the cell depends on cell
content. See
Whether to Focus on a Cell
or an Element Inside
It.
row
element and has one of the
following roles:
row
that can be expanded or
collapsed to show or hide a set
of child rows is a parent row.
Each parent row
has the
aria-expanded
state set on either the row
element or on a cell contained
in therow. The aria-expanded
state is set to false
when the child rows are not
displayed and set to true
when the child rows are
displayed. Rows that do not
control display of child rows do
not have the aria-expanded
attribute because, if they were
to have it, they would be
incorrectly described to
assistive technologies as parent
rows.
treegrid
has
aria-multiselectable
set to true. Otherwise, it is a
single-select treegrid, and aria-multiselectable
is either set to false
or the default value of false
is implied.
true
on the selected row or cell, and
it is not present on any other
row or cell in the
treegrid.
true
on cells where editing is
disabled. If edit functions are
disabled for all cells, instead
of setting aria-readonly
to true
on every cell, aria-readonly
may be set to true
on the treegrid
element. Treegrids that do not
provide cell content editing
functions do not include the aria-readonly
attribute on any of their
elements.
treegrid
role is NOT applied to an HTML table
element, then
aria-rowspan
or
aria-colspan
is applied as described in
grid and table
properties.
treegrid
built from an HTML table
that includes cells that span
multiple rows or columns must
use HTML rowspan
and colspan
and must not use aria-rowspan
or aria-colspan.
treegrid
element unless the DOM
descendants are also included in
the aria-owns
attribute.
100, and when the table of contents is
completely collapsed, the splitter has
a value of 0.
0.
100.
aside
complementary
footer
contentinfo
when in context of
the body
element
header
banner
when in context of
the body
element
main
main
nav
navigation
section
region
when it has an
accessible name
using aria-labelledby
or aria-label
banner, main, complementary
and contentinfo
landmarks should be top level
landmarks.
h1-h6) it can be used as the label
for the area using the aria-labelledby
attribute.
aria-label
attribute.
complementary
landmark is a supporting section of
the document, designed to be
complementary to the main content at a
similar level in the DOM hierarchy,
but remains meaningful when separated
from the main content.
complementary
landmarks should be top level
landmarks (e.g. not contained
within any other
landmarks).
region).
complementary
landmark, each should have a
unique label (see
Step 3
above).
aside
element to define a complementary
landmark.
aside
element technique is not being used,
use a role="complementary"
attribute to define a complementary
landmark.
contentinfo
landmark is a way to identify common
information at the bottom of each page
within a website, typically called the
"footer" of the page,
including information such as
copyrights and links to privacy and
accessibility statements.
contentinfo
landmark.
contentinfo
landmark should be a top-level
landmark.
document
and/or application
roles (e.g. typically through
the use of iframe
and frame
elements), each document
or application
role may have one contentinfo
landmark.
contentinfo
landmark, each should have a
unique label (see
Step 3
above).
footer
element defines a contentinfo
landmark when its context is the body
element.
footer
element is not considered a contentinfo
landmark when it is descendant
of any of following elements
(see
HTML Accessibility
Mappings
[HTML-AAM]):
article
aside
main
nav
section
footer
element technique is not being used, a role="contentinfo"
attribute should be used to define a contentinfo
landmark.
form
landmark identifies a region that
contains a collection of items and
objects that, as a whole, combine to
create a form when no other named
landmark is appropriate (e.g. main or
search).
search
landmark instead of the form
landmark when the form is used
for search functionality.
form
landmark should have a label to
help users understand the
purpose of the form.
form
landmark should be visible to
all users (e.g. an h1-h6
element).
form
landmark in an HTML document
should use native host
semantics:
button
input
select
textarea
form
element defines a form
landmark when it has an accessible
name (e.g. aria-labelledby, aria-label
or title).
role="form"
to identify a region of the page; do
not use it to identify every form
field.
main
landmark.
main
landmark should be a top-level
landmark.
document
and/or application
roles (e.g. typically through
the use of iframe
and frame
elements), each document
or application
role may have one main
landmark.
main
element to define a main
landmark.
main
element technique is not being used,
use a role="main"
attribute to define a main
landmark.
Navigation
landmarks provide a way to identify
groups (e.g. lists) of links that are
intended to be used for website or
page content navigation.
navigation
landmark, each should have a
unique label (see
Step 3
above).
navigation
landmark has an identical set of
links as another navigation
landmark on the page, use the
same label for each navigation
landmark.
nav
element to define a navigation
landmark.
nav
element technique is not being used,
use a role="navigation"
attribute to define a navigation
landmark.
region
landmark is a perceivable section of
the page containing content that is
sufficiently important for users to be
able to navigate to the section.
region
landmark must have a
label.
region
landmark, each should have a
unique label (see
Step 3
above).
region
landmark can be used identify
content that named landmarks do
not appropriately
describe.
section
element defines a region
landmark when it has an accessible
name (e.g. aria-labelledby, aria-label
or title).
section
element technique is not being used,
use a role="region"
attribute to define a region
landmark.
search
landmark contains a collection of
items and objects that, as a whole,
combine to create search
functionality.
search
landmark instead of the form
landmark when the form is used
for search functionality.
search
landmark, each should have a
unique label (see
Step 3
above).
search
landmark.
role="search"
attribute defines a search
landmark.
aria-label.
aria-labelledby.
aria-describedby.
label
element for form elements and caption
element for tables. While less
flexible, their simplicity and
reliance on visible text help ensure
robust accessible experiences. Several
of the
naming techniques
highlight specific accessibility
advantages of using HTML features
instead of ARIA attributes.
title
and placeholder
attributes are used as last resort
sources of content for accessible
names. Because the purpose of these
attributes is not naming, their
content typically yields low quality
accessible names that are not
effective.
menu
element is excluded.)
group
element is excluded.)
group
descendants of treeitem
elements and menu
descendants of menuitem
elements are omitted from the
calculation. For example, in the
following tree, the name of the first tree item is
Fruits; Apples, Bananas, and Oranges
are omitted.
aria-label
or aria-labelledby, content contained in the element
and its descendants is hidden from
assistive technology users unless the
descendant content is referenced by aria-labelledby. It is strongly recommended to avoid
using either of these attributes to
override content of one of the above
elements except in rare circumstances
where hiding content from assistive
technology users is beneficial. In
addition, in situations where visible
content is hidden from assistive
technology users by use of one of
these attributes, thorough testing
with assistive technologies is
particularly important.
aria-label
aria-label
property is useful when there is no
visible text content that will serve
as an appropriate accessible
name.
aria-label
property affects assistive technology
users in one of two different ways,
depending on the role of the element
to which it is applied. When applied
to an element with one of the roles
that supports
naming from child content, aria-label
hides descendant content from
assistive technology users and
replaces it with the value of aria-label. However, when applied to nearly any
other type of element, assistive
technologies will render both the
value of aria-label
and the content of the element. For
example, the name of the following
navigation region is
"Product".
aria-label
is applied to an element with
one of the roles that supports
naming from child
content, content contained in the
element and its descendants is
hidden from assistive technology
users. It is strongly
recommended to avoid using aria-label
to override content of one of
these elements except in rare
circumstances where hiding
content from assistive
technology users is
beneficial.
aria-label. They are identified in the
table in the
Accessible Name Guidance by
Role
section.
aria-label
is not rendered visually,
testing with assistive
technologies to ensure the
expected name is presented to
users is particularly
important.
aria-label
values are translated.
aria-labelledby
aria-labelledby
is similar in this situation to using
an HTML label
element with the for
attribute, one significant difference
is that browsers do not automatically
make clicking on the labeling element
activate the labeled element; that is
an author responsibility. However,
HTML label
cannot be used to label a span
element. Fortunately, an HTML input
with type="checkbox"
allows the ARIA switch
role, so when feasible, using the
following approach creates a more
robust solution.
aria-labelledby
property is useful in a wide variety
of situations because:
aria-label.
hidden
attribute, CSS display: none, or CSS visibility: hidden
in the calculated name
string.
aria-labelledby
could be a label for a night switch
control:
aria-labelledby
has highest precedence in name
calculation, in those situations, it
is possible to use aria-labelledby
to reference both the element itself
and the other element. In the
following example, the "Read
more..." link is named by the
element itself and the article's
heading, resulting in a name for the
link of "Read more... 7 ways you
can help save the bees".
aria-labelledby, text content from each referenced
element is concatenated in the order
specified in the aria-labelledby
value. If an element is referenced
more than one time, only the first
reference is processed. When
concatenating content from multiple
elements, browsers trim leading and
trailing white space and separate
content from each element with a
single space.
aria-labelledby
property cannot be chained,
i.e., if an element with aria-labelledby
references another element that
also has aria-labelledby, the aria-labelledby
attribute on the referenced
element will be ignored.
aria-labelledby
more than one time during a name
calculation, the second and any
subsequent references will be
ignored.
aria-labelledby. They are identified in the
table in the
Accessible Name Guidance by
Role
section.
aria-labelledby
is applied to an element with
one of the roles that supports
naming from child
content, content contained in the
element and its descendants is
hidden from assistive technology
users unless it is also
referenced by aria-labelledby. It is strongly recommended to
avoid using this attribute to
override content of one of these
elements except in rare
circumstances where hiding
content from assistive
technology users is
beneficial.
aria-labelledby
can be complex and reference
hidden content, testing with
assistive technologies to ensure
the expected name is presented
to users is particularly
important.
label
element enables authors to identify
content that serves as a label and
associate it with a form control. When
a label
element is associated with a form
control, browsers calculate an
accessible name for the form control
from the label
content.
label
element as follows gives the checkbox
an accessible name.
for
attribute on the label
element. This allows the label and the
form control to be siblings or have
different parents in the DOM, but
requires adding an id
attribute to the form control, which
can be error-prone. When possible, use
the above encapsulation technique for
association instead of the following for
attribute technique.
label
element is an effective technique for
satisfying
Rule 2: Prefer Visible Text. It also satisfies
Rule 3: Prefer Native
Techniques. Native HTML labels offer an
important usability and accessibility
advantage over ARIA labeling
techniques: browsers automatically
make clicking the label equivalent to
clicking the form control. This
increases the hit area of the form
control.
table
and figure
elements can be derived from a child caption
or figcaption
element, respectively. Tables and
figures often have a caption to
explain what they are about, how to
read them, and sometimes giving them
numbers used to refer to them in
surrounding prose. Captions can help
all users better understand content,
but are especially helpful to users of
assistive technologies.
table
element marks up a data table, and can
be provided with a caption using the caption
element. If the table
element does not have aria-label
or aria-labelledby, then the caption
will be used as the accessible name.
For example, the accessible name of
the following table is Special opening
hours.
table
is named using aria-label
or aria-labelledby, then a caption
element, if present, will become an
accessible description. For an
example, see
Describing Tables and Figures
with Captions.
figure
element can be given a caption using
the figcaption
element. The caption can appear before
or after the figure, but it is more
common for figures to have the caption
after.
table
elements, if a figure
is not named using aria-label
or aria-labelledby, the content of the figcaption
element will be used as the accessible
name. However unlike table
elements, if the figcaption
element is not used for the name, it
does not become an accessible
description unless it is referenced by aria-describedby. Nevertheless, assistive
technologies will render the content
of a figcaption
regardless of whether it is used as a
name, description, or neither.
caption
element to name a table
element, or a figcaption
element to name a figure
element, satisfies
Rule 2: Prefer Visible Text
and
Rule 3: Prefer Native
Techniques.
aria-label
or aria-labelledby
attributes), or native markup
techniques (e.g., the HTML label
element, or the alt
attribute of the HTML img
element), browsers calculate an
accessible name from other attributes
as a fallback mechanism. Because the
attributes used in fallback name
calculation are not intended for
naming, they typically yield low
quality accessible names that are not
effective. So, As advised by
Rule 4: Avoid Browser
Fallback, prefer the explicit labeling
techniques described above over
fallback techniques described in this
section.
title
attribute specified. The title
attribute may be used as the
element's fallback accessible
name. The title
attribute is commonly presented
visually as a tooltip when the user
hovers over the element with a
pointing device, which is not
particularly discoverable, and is also
not accessible to visual users without
a pointing device.
fieldset
element without a legend
element child, but with a title
attribute, gets its accessible name
from the title
attribute.
input
and textarea
elements, the placeholder
attribute is used as a fallback
labeling mechanism if nothing else
(including the title
attribute) results in a label. It is
better to use a label
element, since it does not disappear
visually when the user focuses the
form control.
aria-label
or aria-labelledby
is applied, content contained in
the element and its descendants
is hidden from assistive
technology users unless it is
also referenced by aria-labelledby. Avoid hiding descendant
content except in the rare
circumstances where doing so
benefits assistive technology
users.
aria-label
provides a method
for prefacing the
visible content of
an alert with text
that is not
displayed as part of
the alert. Using aria-label
is functionally
equivalent to
providing off-screen
text in the contents
of the alert, except
off-screen text
would be announced
by screen readers
that do not support aria-label
on alert
elements.
aria-labelledby
if a visible label is present,
otherwise use aria-label.
aria-labelledby
if a visible label is present,
otherwise with aria-label.
aria-label
or aria-labelledby
will hide descendant content
from assistive
technologies.
aria-label
or aria-labelledby
will hide descendant content
from assistive
technologies.
cell; the name of a cell in a table
is its content. Headers are
complementary information.
aria-label
or aria-labelledby
will hide any descendant content
from assistive
technologies.
type="checkbox", use a label
element.
aria-labelledby.
aria-label
or aria-labelledby
will hide descendant content
from assistive
technologies.
columnheader
role is implied from an HTML th, the HTML abbr
attribute can be used to specify
an abbreviated version of the
name that is only announced when
screen readers are reading an
associated cell
within the table, grid, or treegrid.
combobox
role is applied to an HTML select
or input
element, can be named with an
HTML label
element.
aria-labelledby
if a visible label is
present.
aria-label
if a visible label is not
present.
aria-labelledby
if a visible label is present,
otherwise use aria-label.
aria-labelledby
if a visible label is present,
otherwise with aria-label.
definition
| Recommended | Reference the term
being defined with role="term", using aria-labelledby. | |
dialog
| Required | Use aria-labelledby
if a visible label is present,
otherwise use aria-label. | |
directory
| Discretionary |
aria-labelledby
if a visible label is present,
otherwise use aria-label.
document
| Discretionary | Elements with the document
role are contained within an element
with the application
role, which is required to have a
name. Typically, the name of the application
element will provide sufficient
context and identity for the document
element. Because the application
element is used only to create
unusual, custom widgets, careful
assessment is necessary to determine
whether or not adding an accessible
name is beneficial. | |
feed
| Recommended |
aria-labelledby
if a visible label is present,
otherwise use aria-label.
figure
and figcaption
elements. The figcaption
will serve as the accessible
name for the figure. See the
Naming Tables and Figures
with Captions
section.
aria-labelledby
on the figure, pointing to the
figure's caption.
aria-label
can be used.
aria-labelledby
if a visible label is present,
otherwise use aria-label.
grid
is applied to an HTML table
element, then the accessible
name can be derived from the
table's caption
element.
aria-labelledby
if a visible label is present,
otherwise use aria-label.
aria-label
or aria-labelledby
will hide descendant content
from assistive
technologies.
gridcell; the name of a cell in a grid
is its content. Headers are
complementary information.
fieldset
element, the accessible name can
be derived from the legend
element.
details
element, do not provide an
accessible name for this
element. The user interacts with
the summary
element, and that can derive its
accessible name from its
contents.
optgroup
element, use the label
attribute.
aria-labelledby
if a visible label is present,
otherwise use aria-label.
aria-label
or aria-labelledby
will hide descendant content
from assistive
technologies.
aria-label
or aria-labelledby
will hide descendant content
from assistive
technologies.
aria-labelledby
if a visible label is present,
otherwise with aria-label.
listbox
role is applied to an HTML select
element (with the multiple
attribute or a size
attribute having a value greater
than 1), can be named with an
HTML label
element.
aria-labelledby
if a visible label is
present.
aria-label
if a visible label is not
present.
aria-labelledby
if a visible label is present,
otherwise with aria-label.
math
element has only presentational
children and the accessible name
is intended to convey the
mathematical expression, use aria-label
to provide a string that
represents the expression.
math
element contains navigable
content that conveys the
mathematical expression and a
visible label for the expression
is present, use aria-labelledby.
aria-label
to name the expression, e.g., aria-label="Pythagorean
Theorem".
aria-labelledby
to refer to the menuitem or
button that controls this
element's display.
aria-label.
menuitem
elements in a menubar. Naming a menubar
is comparable to naming a menu
button. The name of a button
that opens a menu
conveys the purpose of the menu
it opens. Since a menubar
element is displayed
persistently, a name on the menubar
can serve that same
purpose.
aria-labelledby
if a visible label is present,
otherwise use aria-label.
aria-label
or aria-labelledby
will hide any descendant content
from assistive
technologies.
menu
is automatically excluded from
the accessible name
calculation.
aria-label
or aria-labelledby
will hide any descendant content
from assistive
technologies.
aria-label
or aria-labelledby
will hide any descendant content
from assistive
technologies.
aria-labelledby
if a visible label is present,
otherwise use aria-label.
aria-labelledby
if a visible label is present,
otherwise with aria-label.
aria-label
or aria-labelledby
will hide any descendant content
from assistive
technologies.
presentation
| Do Not Name | An element with role="presentation"
is not part of the accessibility tree
(except in error cases). Do not use aria-labelledby
or aria-label. | |
progressbar
| Required |
progressbar
role is applied to an HTML progress
element, can be named with an
HTML label
element.
aria-labelledby
if a visible label is
present.
aria-label
if a visible label is not
present.
aria-label
or aria-labelledby
will hide any descendant content
from assistive
technologies.
type="checkbox", use a label
element.
aria-labelledby.
radio
buttons.
aria-labelledby
if a visible label is present,
otherwise use aria-label.
aria-labelledby
if a visible label is present,
otherwise use aria-label.
row
| Required Only If
Content Insufficient AND
descendant of a treegrid
AND
the row is focusable | When row
elements are focusable in a
treegrid, screen readers announce the entire
contents of a row when navigating by
row. This is typically the most
appropriate behavior. However, in some
circumstances, it could be beneficial
to change the order in which cells are
announced or exclude announcement of
certain cells by using aria-labelledby
to specify which cells to announce. |
|
rowgroup
| Do Not Name | Not supported by
assistive technologies. | |
rowheader
| Required Only If
Content Insufficient |
aria-label
or aria-labelledby
will hide descendant content
from assistive
technologies.
rowheader
role is implied from an HTML th, the HTML abbr
attribute can be used to specify
an abbreviated version of the
name that is only announced when
screen readers are reading an
associated cell
within the table, grid, or treegrid.
aria-controls
attribute, which is required for scrollbar.
aria-labelledby
if a visible label is present,
otherwise with aria-label.
aria-labelledby
if a visible label is present,
otherwise with aria-label.
searchbox
role is applied to an HTML input
element, can be named with an
HTML label
element.
aria-labelledby
if a visible label is
present.
aria-label
if a visible label is not
present.
separator
element on the page.
aria-labelledby
if a visible label is present,
otherwise with aria-label.
slider
role is applied to an HTML input
element, can be named with an
HTML label
element.
aria-labelledby
if a visible label is
present.
aria-label
if a visible label is not
present.
textbox
role is applied to an HTML input
element, can be named with an
HTML label
element.
aria-labelledby
if a visible label is
present.
aria-label
if a visible label is not
present.
status
| Discretionary | Some screen readers
announce the name of a status element
before announcing the content of the
status element. Thus, aria-label
provides a method for prefacing the
visible content of a status element
with text that is not displayed as
part of the status element. Using aria-label
is functionally equivalent to
providing off-screen text in the
contents of the status element, except
off-screen text would be announced by
screen readers that do not support aria-label
on status
elements. | |
switch
| Required Only If
Content Insufficient |
aria-label
or aria-labelledby
will hide any descendant content
from assistive
technologies.
type="checkbox", use a label
element.
aria-labelledby.
aria-label
or aria-labelledby
will hide descendant content
from assistive
technologies.
table
element, use the caption
element.
aria-labelledby
if a visible label is
present.
aria-label
if a visible label is not
present.
aria-labelledby
if a visible label is present,
otherwise use aria-label.
aria-labelledby
pointing to the tab
element that controls the tabpanel.
textbox
role is applied to an HTML input
or textarea
element, can be named with an
HTML label
element.
aria-labelledby
if a visible label is
present.
aria-label
if a visible label is not
present.
toolbar
element on the page, naming is
required.
aria-labelledby
if a visible label is present,
otherwise use aria-label.
aria-label
or aria-labelledby
will hide descendant content
from assistive
technologies.
aria-labelledby
if a visible label is present,
otherwise use aria-label.
treegrid
is applied to an HTML table
element, then the accessible
name can be derived from the
table's caption
element.
aria-labelledby
if a visible label is present,
otherwise use aria-label.
aria-label
or aria-labelledby
will hide any descendant content
from assistive
technologies.
group
is automatically excluded from
the accessible name
calculation.
aria-labelledby
property is used if
present.
aria-label
property is used if
present.
input
whose type
attribute is in the Button,
Submit Button, or Reset Button
state
value
attribute.
input
whose type
attribute is in the Image Button
state
img
area
alt
attribute.
fieldset
legend
element.
label
element(s).
figure
figcaption
element.
table
caption
element.
input
whose type
attribute is in the Text,
Password, Search, Telephone, or
URL states
textarea
title
attribute. Otherwise, the placeholder
attribute.
input
whose type
attribute is in the Submit
Button state
input
whose type
attribute is in the Reset Button
state
input
whose type
attribute is in the Image Button
state
title
attribute. Otherwise, a
localized string of the phrase
"Submit Query".
summary
title
attribute.
treeitem
and menuitem
as described below. And, when
following references in an aria-labelledby
attribute, it similarly walks the tree
of each referenced element. Thus, the
naming algorithm is recursive. The
following two sections explain
non-recursive and recursive examples
of how the algorithm works.
treeitem
role, descendant content of child group
elements are not included. For
example, in the following tree, the name of the first tree item is
Fruits; Apples, Bananas, and Oranges
are automatically omitted.
menuitem
role, descendant content of child menu
elements are not included. So, the
name of the first parent menuitem
in the following menu
is Fruits.
input
element that has no associated label
element and only a name
attribute and so does not have an
accessible name (do not do
this):
placeholder
attribute, then it serves as a naming
fallback mechanism (avoid doing
this):
title
attribute, then it is used as the
accessible name instead of placeholder, but it is still a fallback (avoid
doing this):
label
element (recommended), then that is
used as the accessible name, and the title
attribute is instead used as the
accessible description:
aria-label
attribute (not recommended unless it
adds clarity for assistive technology
users), then that becomes the
accessible name, overriding the label
element:
aria-labelledby
attribute, that wins over the other
elements and attributes (the aria-label
attribute ought to be removed if it is
not used):
aria-labelledby
reference causes the algorithm to be
invoked recursively, and when
computing an accessible name from
content the algorithm is invoked
recursively for each child node.
aria-labelledby
reference, the algorithm avoids
following the same reference twice to
avoid infinite loops.
aria-labelledby
reference to the parent element, and
then computing the label for that
element from the child nodes, first
visiting the button
element again but ignoring the aria-labelledby
reference and instead using the aria-label, and then visiting the next child
(the text node). The resulting label
is Remove meeting: Daily status
report.
aria-describedby
aria-describedby
property works similarly to the aria-labelledby
property. For example, a button could
be described by a sibling
paragraph.
img
element, a text equivalent of the
image is computed.
aria-labelledby, it is possible to reference an
element using aria-describedby
even if that element is hidden. For
example, a text field in a form could
have a description that is hidden by
default, but can be revealed on
request using a disclosure widget. The
description could also be referenced
from the text field directly with aria-describedby. In the following example, the
accessible description for the input
element is Your username is the name
that you use to log in to this
service.
table
is named using aria-label
or aria-labelledby, a child caption
element becomes an accessible
description. For example, a preceding
heading might serve as an appropriate
accessible name, and the caption
element might contain a longer
description. In such a situation, aria-labelledby
could be used on the table
to set the accessible name to the
heading content and the caption
would become the accessible
description.
figure
element can get its accessible name
from its figcaption
element, but it will not be used as
the accessible description, even if it was not used as the
accessible name. If the figcaption
element is appropriate as an
accessible description, and the
accessible name is set using aria-labelledby
or aria-label, then the figcaption
can be explicitly set as the
accessible description using the aria-describedby
attribute.
aria-describedby
attribute or one of the primary
host-language-specific attributes or
elements (e.g., the caption
element for table), then, for HTML, if the element has
a title
attribute, that is used as the
accessible description.
aria-describedby
is generally recommended. If a
description that is not visible is
desired, then the title
attribute can be used, for any HTML
element that can have an accessible
description.
title
attribute might not be accessible to
some users, in particular sighted
users not using a screen reader and
not using a pointing device that
supports hover (e.g., a mouse).
input
element with input constrained using
the pattern
attribute can use the title
attribute to describe what the
expected input is.
title
attribute in this case can be shown to
the user as a tooltip when the user
hovers or focuses the control, but
also as part of the error message when
the user agent validates the form, if
the input
element's value doesn't
match the pattern.
title
attribute to describe the link in more
detail.
aria-describedby
instead of aria-labelledby.
aria-describedby
property is used if
present.
input
whose type
attribute is in the Button,
Submit Button, or Reset Button
state
value
attribute.
summary
table
caption
element.
title
attribute.
aria-selected="true".
tabindex="0"
on the element that will
initially be included in the tab
sequence and set tabindex="-1"
on all other focusable elements
it contains.
tabindex="-1"
on the element that has tabindex="0".
tabindex="0"
on the element that will
become focused as a
result of the key
event.
element.focus(), on the element that
has tabindex="0".
tabindex="0"
when the composite loses focus.
If it does not, set tabindex="0"
on the target element and set tabindex="-1"
on the element that previously
had tabindex="0".
aria-activedescendant="IDREF"
where IDREF is the ID of
the element within the
container that should be
identified as active
when the widget receives
focus. The referenced
element needs to meet
the DOM relationship
requirements described
below.
aria-colcount
table, grid, or treegrid.
aria-rowcount
table, grid, or treegrid.
aria-colindex
table, grid, or treegrid.
aria-rowindex
|
table, grid, or treegrid.
aria-colspan
| Defines the number of columns
spanned by a cell or gridcell within a table, grid, or treegrid. | | aria-rowspan
| Defines the number of rows spanned
by a cell or gridcell within a table, grid, or treegrid. | | aria-sort
| Indicates if items in a row or
column are sorted in ascending or
descending order. |
aria-rowcount
and aria-rowindex
aria-rowcount
property is used to communicate the
total number of rows available, and it
is accompanied by the aria-rowindex
property to identify the row indices
of the rows that are present in the
DOM.
aria-rowcount
is specified on the element with the table, grid, or treegrid
role. Its value is an integer equal to
the total number of rows available,
including header rows. If the total
number of rows is unknown, a value of -1
may be specified. Using a value of -1
indicates that more rows are available
to include in the DOM without
specifying the size of the available
supply.
aria-rowcount
is used on a table, grid, or treegrid, a value for aria-rowindex
property is specified on each of its
descendant rows, including any header
rows. The value of aria-rowindex
is an integer that is:
aria-rowindex
on any previous rows.
aria-rowindex
could have devastating effects on
assistive technology behavior. For
example, specifying an invalid value
for aria-rowindex
or setting it on some but not all rows
in a table, could cause screen reader
table reading functions to skip rows
or simply stop functioning.
aria-rowcount
and aria-rowindex
properties on a table containing a
hypothetical class list.
aria-colcount
and aria-colindex
aria-colcount
property is used to communicate the
total number of columns available, and
it is accompanied by the aria-colindex
property to identify the column
indices of the columns that are
present in the DOM.
aria-colcount
is specified on the element with the table, grid, or treegrid
role. Its value is an integer equal to
the total number of columns available.
If the total number of columns is
unknown, a value of -1
may be specified. Using a value of -1
indicates that more columns are
available to include in the DOM
without specifying the size of the
available supply.
aria-colcount
is used on a table, grid, or treegrid, a value for aria-colindex
property is either specified on each
of its descendant rows or on every
cell in each descendant row, depending
on whether the columns are contiguous
as described below. The value of aria-colindex
is an integer that is:
aria-colindex
could have devastating effects on
assistive technology behavior. For
example, specifying an invalid value
for aria-colindex
or setting it on some but not all
cells in a row, could cause screen
reader table reading functions to skip
cells or simply stop
functioning.
aria-colindex
When Column Indices Are
Contiguous
aria-colindex
can be set on the row element with a
value equal to the index number of the
first column in the set. Browsers will
then compute a column number for each
cell in the row.
aria-colindex
can be placed on each row.
aria-colindex
When Column Indices Are Not
Contiguous
aria-colindex
needs to be set on each cell in the
row. The following example shows a
grid for an online grade book where
the first two columns contain a
student name and subsequent columns
contain scores. In this example, the
first two columns with the student
name are shown, but the score columns
have been scrolled to show columns 10
through 13. Columns 3 through 9 are
not visible so are not in the
DOM.
aria-colspan
and aria-rowspan
table
elements, row and column spans are
defined with the aria-rowspan
and aria-colspan
properties.
aria-colspan
is an integer that is:
aria-rowspan
is an integer that is:
table
elements, use the native semantics of
the th
and td
elements to define row and column
spans by using the rowspan
and colspan
attributes.
aria-sort
aria-sort
property can be applied to a column or
row header to indicate the sorting
method. The following table describes
allowed values for aria-sort.
aria-sort
ascending
descending
other
none
aria-sort
with a value other than none
to more than one column or row.
aria-sort
to indicate the rows are sorted from
the highest "Quiz 2" score
to the lowest "Quiz 2"
score.
presentation
Role
presentation.
ul
element.
presentation
to the li
elements tells browsers to leave those
elements out of their accessibility
tree. Assistive technologies will thus
be unaware of the list item elements
and see the tab elements as immediate
children of the tablist.
presentation
are:
presentation
role="presentation"
is specified on an element, if a
condition that requires a browser
to ignore the presentation
role
does not exist, it has the following
three effects.
display: none
or has aria-hidden="true".
presentation
is applied to a ul
or ol
element, each child li
element inherits the presentation
role because ARIA
requires the listitem
elements to have the
parent list
element. So, the li
elements are not exposed
to assistive
technologies, but
elements contained
inside of those li
elements, including
nested lists, are
visible to assistive
technologies.
presentation
is applied to a table
element, the descendant caption, thead, tbody, tfoot, tr, th, and td
elements inherit role presentation
and are thus not exposed
to assistive
technologies. But,
elements inside of the th
and td
elements, including
nested tables, are
exposed to assistive
technologies.
presentation
to be Ignored
role="presentation", and it therefore has no effect, if
either of the following are true about
the element to which it is
applied:
tabindex
attribute.
presentation
Role
presentation
to all descendant elements of any
element with a role that cannot
support semantic children.
button
role.
data-
attributes instead of
with rel
attributes.